<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">

<title>tutorial - RDoc Documentation</title>


<script src="../js/navigation.js" defer></script>
<script src="../js/search.js" defer></script>
<script src="../js/search_index.js" defer></script>
<script src="../js/searcher.js" defer></script>
<script src="../js/darkfish.js" defer></script>

<script src="../js/jquery-3.2.0.min.js"></script>

<script src="../js/vue.min.js"></script>
<script src="../js/js.cookie.min.js"></script>

<link href="../css/fonts.css" rel="stylesheet">
<link id='rdoccss' href="../css/rdoc.css" rel="stylesheet">
<link href="../css/carbon17.css" rel="stylesheet">

<script type="text/javascript">
  var rdoc_rel_prefix = "../";
  var index_rel_prefix = "../";
  var darkModeCsseHref = "../css/rdoc-dm.css"
  var defaultModeCssHref = "../css/rdoc.css"
  // var cssDarkmode = Cookies.get('darkmode');
  
  if( Cookies.get("darkmode") == "true") {
	$('#rdoccss').attr("href", darkModeCsseHref);
}

//  https://cssdeck.com/blog/simple-jquery-stylesheet-switcher/

document.write('<style type="text/css">body{display:none}</style>');

</script>


</head>
<body id="top" role="document" class="file">
  <!-- this is page.html -->
  <div id='actionbar' >
    <div class='wrapper mdiv'>
      <ul class='grids g0'></ul>
    </div> 
    <!-- VERSION HEADER for 3.3.0-preview2 NOT FOUND -->
  </div> <!-- end action bar -->


 <div class='wrapper hdiv'>

 


<nav id='vapp' role="navigation">
  <div id="project-navigation">
    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
  <h2><a href="../index.html" rel="home">Home</a></h2>

  <div id="table-of-contents-navigation"  >
    <a href="../table_of_contents.html#pages">Pages</a>
    <a href="../table_of_contents.html#classes">Classes</a>
    <a href="../table_of_contents.html#methods">Methods</a>
  </div>
</div>

    <div id="search-section" role="search" class="project-section initially-hidden">
  <form action="#" method="get" accept-charset="utf-8">
    <div id="search-field-wrapper">
      <input id="search-field" role="combobox" aria-label="Search"
             aria-autocomplete="list" aria-controls="search-results"
             type="text" name="search" placeholder="Search" spellcheck="false"
             title="Type to search, Up and Down to navigate, Enter to load">
    </div>

    <ul id="search-results" aria-label="Search Results"
        aria-busy="false" aria-expanded="false"
        aria-atomic="false" class="initially-hidden"></ul>
  </form>
</div>

  </div>

  
<div class="nav-section">
  <h3>Table of Contents</h3>

  <ul class="link-list" role="directory">
    <li><a href="#label-Tutorial">Tutorial</a>
    <li><a href="#label-Why+OptionParser-3F">Why <code>OptionParser</code>?</a>
    <li><a href="#label-Contents">Contents</a>
    <li><a href="#label-To+Begin+With">To Begin With</a>
    <li><a href="#label-Defining+Options">Defining Options</a>
    <li><a href="#label-Option+Names">Option Names</a>
    <li><a href="#label-Short+Option+Names">Short Option Names</a>
    <li><a href="#label-Long+Option+Names">Long Option Names</a>
    <li><a href="#label-Mixing+Option+Names">Mixing Option Names</a>
    <li><a href="#label-Option+Name+Abbreviations">Option Name Abbreviations</a>
    <li><a href="#label-Option+Arguments">Option Arguments</a>
    <li><a href="#label-Option+with+No+Argument">Option with No Argument</a>
    <li><a href="#label-Option+with+Required+Argument">Option with Required Argument</a>
    <li><a href="#label-Option+with+Optional+Argument">Option with Optional Argument</a>
    <li><a href="#label-Argument+Values">Argument Values</a>
    <li><a href="#label-Explicit+Argument+Values">Explicit Argument Values</a>
    <li><a href="#label-Explicit+Values+in+Array">Explicit Values in Array</a>
    <li><a href="#label-Explicit+Values+in+Hash">Explicit Values in Hash</a>
    <li><a href="#label-Argument+Value+Patterns">Argument Value Patterns</a>
    <li><a href="#label-Keyword+Argument+into">Keyword Argument <code>into</code></a>
    <li><a href="#label-Collecting+Options">Collecting Options</a>
    <li><a href="#label-Checking+for+Missing+Options">Checking for Missing Options</a>
    <li><a href="#label-Default+Values+for+Options">Default Values for Options</a>
    <li><a href="#label-Argument+Converters">Argument Converters</a>
    <li><a href="#label-Help">Help</a>
    <li><a href="#label-Top+List+and+Base+List">Top List and Base List</a>
    <li><a href="#label-Methods+for+Defining+Options">Methods for Defining Options</a>
    <li><a href="#label-Parsing">Parsing</a>
    <li><a href="#label-Method+parse-21">Method <code>parse!</code></a>
    <li><a href="#label-Method+parse">Method <code>parse</code></a>
    <li><a href="#label-Method+order-21">Method <code>order!</code></a>
    <li><a href="#label-Method+order">Method <code>order</code></a>
    <li><a href="#label-Method+permute-21">Method <code>permute!</code></a>
    <li><a href="#label-Method+permute">Method <code>permute</code></a>
  </ul>
</div>

  <button id='toggleThing' @click="toggleNav()" >Show/hide navigation</button>

  <div id="project-metadata">
   <div :class="isOpen ? 'block' : 'hidden' " id='toggleMe'>
    
<div id="fileindex-section" class="nav-section">
  <h3>Pages</h3>

  <ul class="link-list">
    <li><a href="../NEWS/NEWS-1_8_7.html">NEWS-1.8.7</a>
    <li><a href="../NEWS/NEWS-1_9_1.html">NEWS-1.9.1</a>
    <li><a href="../NEWS/NEWS-1_9_2.html">NEWS-1.9.2</a>
    <li><a href="../NEWS/NEWS-1_9_3.html">NEWS-1.9.3</a>
    <li><a href="../NEWS/NEWS-2_0_0.html">NEWS-2.0.0</a>
    <li><a href="../NEWS/NEWS-2_1_0.html">NEWS-2.1.0</a>
    <li><a href="../NEWS/NEWS-2_2_0.html">NEWS-2.2.0</a>
    <li><a href="../NEWS/NEWS-2_3_0.html">NEWS-2.3.0</a>
    <li><a href="../NEWS/NEWS-2_4_0.html">NEWS-2.4.0</a>
    <li><a href="../NEWS/NEWS-2_5_0.html">NEWS-2.5.0</a>
    <li><a href="../NEWS/NEWS-2_6_0.html">NEWS-2.6.0</a>
    <li><a href="../NEWS/NEWS-2_7_0.html">NEWS-2.7.0</a>
    <li><a href="../NEWS/NEWS-3_0_0_md.html">NEWS-3.0.0</a>
    <li><a href="../NEWS/NEWS-3_1_0_md.html">NEWS-3.1.0</a>
    <li><a href="../NEWS/NEWS-3_2_0_md.html">NEWS-3.2.0</a>
    <li><a href="../bsearch_rdoc.html">bsearch</a>
    <li><a href="../bug_triaging_rdoc.html">bug_triaging</a>
    <li><a href="../case_mapping_rdoc.html">case_mapping</a>
    <li><a href="../character_selectors_rdoc.html">character_selectors</a>
    <li><a href="../command_injection_rdoc.html">command_injection</a>
    <li><a href="../contributing_md.html">contributing</a>
    <li><a href="../contributing/building_ruby_md.html">building_ruby</a>
    <li><a href="../contributing/documentation_guide_md.html">documentation_guide</a>
    <li><a href="../contributing/glossary_md.html">glossary</a>
    <li><a href="../contributing/making_changes_to_ruby_md.html">making_changes_to_ruby</a>
    <li><a href="../contributing/making_changes_to_stdlibs_md.html">making_changes_to_stdlibs</a>
    <li><a href="../contributing/reporting_issues_md.html">reporting_issues</a>
    <li><a href="../contributing/testing_ruby_md.html">testing_ruby</a>
    <li><a href="../dig_methods_rdoc.html">dig_methods</a>
    <li><a href="../distribution_md.html">distribution</a>
    <li><a href="../dtrace_probes_rdoc.html">dtrace_probes</a>
    <li><a href="../encodings_rdoc.html">encodings</a>
    <li><a href="../extension_ja_rdoc.html">extension.ja</a>
    <li><a href="../extension_rdoc.html">extension</a>
    <li><a href="../fiber_md.html">fiber</a>
    <li><a href="../format_specifications_rdoc.html">format_specifications</a>
    <li><a href="../globals_rdoc.html">globals</a>
    <li><a href="../implicit_conversion_rdoc.html">implicit_conversion</a>
    <li><a href="../keywords_rdoc.html">keywords</a>
    <li><a href="../maintainers_md.html">maintainers</a>
    <li><a href="../marshal_rdoc.html">marshal</a>
    <li><a href="../memory_view_md.html">memory_view</a>
    <li><a href="../optparse/argument_converters_rdoc.html">argument_converters</a>
    <li><a href="../optparse/creates_option_rdoc.html">creates_option</a>
    <li><a href="../optparse/option_params_rdoc.html">option_params</a>
    <li><a href="../optparse/tutorial_rdoc.html">tutorial</a>
    <li><a href="../packed_data_rdoc.html">packed_data</a>
    <li><a href="../ractor_md.html">ractor</a>
    <li><a href="../regexp_rdoc.html">regexp</a>
    <li><a href="../regexp/methods_rdoc.html">methods</a>
    <li><a href="../regexp/unicode_properties_rdoc.html">unicode_properties</a>
    <li><a href="../ruby_3_3_0_preview2/COPYING.html">COPYING</a>
    <li><a href="../ruby_3_3_0_preview2/COPYING_ja.html">COPYING.ja</a>
    <li><a href="../ruby_3_3_0_preview2/LEGAL.html">LEGAL</a>
    <li><a href="../ruby_3_3_0_preview2/NEWS_md.html">NEWS</a>
    <li><a href="../ruby_3_3_0_preview2/README_ja_md.html">README.ja</a>
    <li><a href="../ruby_3_3_0_preview2/README_md.html">README</a>
    <li><a href="../security_rdoc.html">security</a>
    <li><a href="../signals_rdoc.html">signals</a>
    <li><a href="../standard_library_rdoc.html">standard_library</a>
    <li><a href="../strftime_formatting_rdoc.html">strftime_formatting</a>
    <li><a href="../syntax_rdoc.html">syntax</a>
    <li><a href="../syntax/assignment_rdoc.html">assignment</a>
    <li><a href="../syntax/calling_methods_rdoc.html">calling_methods</a>
    <li><a href="../syntax/comments_rdoc.html">comments</a>
    <li><a href="../syntax/control_expressions_rdoc.html">control_expressions</a>
    <li><a href="../syntax/exceptions_rdoc.html">exceptions</a>
    <li><a href="../syntax/literals_rdoc.html">literals</a>
    <li><a href="../syntax/methods_rdoc.html">methods</a>
    <li><a href="../syntax/miscellaneous_rdoc.html">miscellaneous</a>
    <li><a href="../syntax/modules_and_classes_rdoc.html">modules_and_classes</a>
    <li><a href="../syntax/pattern_matching_rdoc.html">pattern_matching</a>
    <li><a href="../syntax/precedence_rdoc.html">precedence</a>
    <li><a href="../syntax/refinements_rdoc.html">refinements</a>
    <li><a href="../timezones_rdoc.html">timezones</a>
    <li><a href="../windows_md.html">windows</a>
    <li><a href="../yjit/yjit_md.html">yjit</a>
    <li><a href="../yjit/yjit_hacking_md.html">yjit_hacking</a>
  </ul>
</div>

   </div>
  </div>
</nav>


<!--  carbon ads here -->

<div id='extraz'>
  <div class='adzbox-index'  >
   
  </div>
 </div>         


<main role="main" aria-label="Page optparse/tutorial.rdoc">

<h2 id="label-Tutorial">Tutorial<span><a href="#label-Tutorial">&para;</a> <a href="#top">&uarr;</a></span></h2>

<h3 id="label-Why+OptionParser-3F">Why <code>OptionParser</code>?<span><a href="#label-Why+OptionParser-3F">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>When a Ruby program executes, it captures its command-line arguments and options into variable ARGV. This simple program just prints its <code>ARGV</code>:</p>

<pre class="ruby"><span class="ruby-identifier">p</span> <span class="ruby-constant">ARGV</span>
</pre>

<p>Execution, with arguments and options:</p>

<pre>$ ruby argv.rb foo --bar --baz bat bam
[&quot;foo&quot;, &quot;--bar&quot;, &quot;--baz&quot;, &quot;bat&quot;, &quot;bam&quot;]</pre>

<p>The executing program is responsible for parsing and handling the command-line options.</p>

<p>OptionParser offers methods for parsing and handling those options.</p>

<p>With <code>OptionParser</code>, you can define options so that for each option:</p>
<ul><li>
<p>The code that defines the option and code that handles that option are in the same place.</p>
</li><li>
<p>The option may take no argument, a required argument, or an optional argument.</p>
</li><li>
<p>The argument may be automatically converted to a specified class.</p>
</li><li>
<p>The argument may be restricted to specified <em>forms</em>.</p>
</li><li>
<p>The argument may be restricted to specified <em>values</em>.</p>
</li></ul>

<p>The class also has method help, which displays automatically-generated help text.</p>

<h3 id="label-Contents">Contents<span><a href="#label-Contents">&para;</a> <a href="#top">&uarr;</a></span></h3>
<ul><li>
<p><a href="#label-To+Begin+With">To Begin With</a></p>
</li><li>
<p><a href="#label-Defining+Options">Defining Options</a></p>
</li><li>
<p><a href="#label-Option+Names">Option Names</a></p>
<ul><li>
<p><a href="#label-Short+Option+Names">Short Option Names</a></p>
</li><li>
<p><a href="#label-Long+Option+Names">Long Option Names</a></p>
</li><li>
<p><a href="#label-Mixing+Option+Names">Mixing Option Names</a></p>
</li><li>
<p><a href="#label-Option+Name+Abbreviations">Option Name Abbreviations</a></p>
</li></ul>
</li><li>
<p><a href="#label-Option+Arguments">Option Arguments</a></p>
<ul><li>
<p><a href="#label-Option+with+No+Argument">Option with No Argument</a></p>
</li><li>
<p><a href="#label-Option+with+Required+Argument">Option with Required Argument</a></p>
</li><li>
<p><a href="#label-Option+with+Optional+Argument">Option with Optional Argument</a></p>
</li><li>
<p><a href="#label-Argument+Abbreviations">Argument Abbreviations</a></p>
</li></ul>
</li><li>
<p><a href="#label-Argument+Values">Argument Values</a></p>
<ul><li>
<p><a href="#label-Explicit+Argument+Values">Explicit Argument Values</a></p>
<ul><li>
<p><a href="#label-Explicit+Values+in+Array">Explicit Values in Array</a></p>
</li><li>
<p><a href="#label-Explicit+Values+in+Hash">Explicit Values in Hash</a></p>
</li></ul>
</li><li>
<p><a href="#label-Argument+Value+Patterns">Argument Value Patterns</a></p>
</li></ul>
</li><li>
<p><a href="#label-Keyword+Argument+into">Keyword Argument into</a></p>
<ul><li>
<p><a href="#label-Collecting+Options">Collecting Options</a></p>
</li><li>
<p><a href="#label-Checking+for+Missing+Options">Checking for Missing Options</a></p>
</li><li>
<p><a href="#label-Default+Values+for+Options">Default Values for Options</a></p>
</li></ul>
</li><li>
<p><a href="#label-Argument+Converters">Argument Converters</a></p>
</li><li>
<p><a href="#label-Help">Help</a></p>
</li><li>
<p><a href="#label-Top+List+and+Base+List">Top List and Base List</a></p>
</li><li>
<p><a href="#label-Methods+for+Defining+Options">Methods for Defining Options</a></p>
</li><li>
<p><a href="#label-Parsing">Parsing</a></p>
<ul><li>
<p><a href="#label-Method+parse-21">Method parse!</a></p>
</li><li>
<p><a href="#label-Method+parse">Method parse</a></p>
</li><li>
<p><a href="#label-Method+order-21">Method order!</a></p>
</li><li>
<p><a href="#label-Method+order">Method order</a></p>
</li><li>
<p><a href="#label-Method+permute-21">Method permute!</a></p>
</li><li>
<p><a href="#label-Method+permute">Method permute</a></p>
</li></ul>
</li></ul>

<h3 id="label-To+Begin+With">To Begin With<span><a href="#label-To+Begin+With">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>To use <code>OptionParser</code>:</p>
<ol><li>
<p>Require the <code>OptionParser</code> code.</p>
</li><li>
<p>Create an <code>OptionParser</code> object.</p>
</li><li>
<p>Define one or more options.</p>
</li><li>
<p>Parse the command line.</p>
</li></ol>

<p><a href="../File.html"><code>File</code></a> <code>basic.rb</code> defines three options, <code>-x</code>, <code>-y</code>, and <code>-z</code>, each with a descriptive string, and each with a block.</p>

<pre class="ruby"><span class="ruby-comment"># Require the OptionParser code.</span>
<span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-comment"># Create an OptionParser object.</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-comment"># Define one or more options.</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;Whether to X&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;x&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-y&#39;</span>, <span class="ruby-string">&#39;Whether to Y&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;y&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-z&#39;</span>, <span class="ruby-string">&#39;Whether to Z&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;z&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># Parse the command line and return pared-down ARGV.</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>From these defined options, the parser automatically builds help text:</p>

<pre>$ ruby basic.rb --help
Usage: basic [options]
    -x                               Whether to X
    -y                               Whether to Y
    -z                               Whether to Z</pre>

<p>When an option is found during parsing, the block defined for the option is called with the argument value. An invalid option raises an exception.</p>

<p><a href="../Method.html"><code>Method</code></a> parse!, which is used most often in this tutorial, removes from <code>ARGV</code> the options and arguments it finds, leaving other non-option arguments for the program to handle on its own. The method returns the possibly-reduced <code>ARGV</code> array.</p>

<p>Executions:</p>

<pre>$ ruby basic.rb -x -z
[&quot;x&quot;, true]
[&quot;z&quot;, true]
[]
$ ruby basic.rb -z -y -x
[&quot;z&quot;, true]
[&quot;y&quot;, true]
[&quot;x&quot;, true]
[]
$ ruby basic.rb -x input_file.txt output_file.txt
[&quot;x&quot;, true]
[&quot;input_file.txt&quot;, &quot;output_file.txt&quot;]
$ ruby basic.rb -a
basic.rb:16:in `&lt;main&gt;&#39;: invalid option: -a (OptionParser::InvalidOption)</pre>

<h3 id="label-Defining+Options">Defining Options<span><a href="#label-Defining+Options">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>A common way to define an option in <code>OptionParser</code> is with instance method OptionParser#on.</p>

<p>The method may be called with any number of arguments (whose order does not matter), and may also have a trailing optional keyword argument <code>into</code>.</p>

<p>The given arguments determine the characteristics of the new option. These may include:</p>
<ul><li>
<p>One or more short option names.</p>
</li><li>
<p>One or more long option names.</p>
</li><li>
<p>Whether the option takes no argument, an optional argument, or a required argument.</p>
</li><li>
<p>Acceptable <em>forms</em> for the argument.</p>
</li><li>
<p>Acceptable <em>values</em> for the argument.</p>
</li><li>
<p>A proc or method to be called when the parser encounters the option.</p>
</li><li>
<p><a href="../String.html"><code>String</code></a> descriptions for the option.</p>
</li></ul>

<h3 id="label-Option+Names">Option Names<span><a href="#label-Option+Names">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>You can give an option one or more names of two types:</p>
<ul><li>
<p>Short (1-character) name, beginning with one hyphen (<code>-</code>).</p>
</li><li>
<p>Long (multi-character) name, beginning with two hyphens (<code>--</code>).</p>
</li></ul>

<h4 id="label-Short+Option+Names">Short Option Names<span><a href="#label-Short+Option+Names">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>A short option name consists of a hyphen and a single character.</p>

<p><a href="../File.html"><code>File</code></a> <code>short_names.rb</code> defines an option with a short name, <code>-x</code>, and an option with two short names (aliases, in effect) <code>-y</code> and <code>-z</code>.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;Short name&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;x&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-1&#39;</span>, <span class="ruby-string">&#39;-%&#39;</span>, <span class="ruby-string">&#39;Two short names&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;-1 or -%&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby short_names.rb --help
Usage: short_names [options]
    -x                               Short name
    -1, -%                           Two short names
$ ruby short_names.rb -x
[&quot;x&quot;, true]
$ ruby short_names.rb -1
[&quot;-1 or -%&quot;, true]
$ ruby short_names.rb -%
[&quot;-1 or -%&quot;, true]</pre>

<p>Multiple short names can “share” a hyphen:</p>

<pre>$ ruby short_names.rb -x1%
[&quot;x&quot;, true]
[&quot;-1 or -%&quot;, true]
[&quot;-1 or -%&quot;, true]</pre>

<h4 id="label-Long+Option+Names">Long Option Names<span><a href="#label-Long+Option+Names">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>A long option name consists of two hyphens and a one or more characters (usually two or more characters).</p>

<p><a href="../File.html"><code>File</code></a> <code>long_names.rb</code> defines an option with a long name, <code>--xxx</code>, and an option with two long names (aliases, in effect) <code>--y1%</code> and <code>--z2#</code>.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-string">&#39;Long name&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;-xxx&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--y1%&#39;</span>, <span class="ruby-string">&#39;--z2#&#39;</span>, <span class="ruby-string">&quot;Two long names&quot;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--y1% or --z2#&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby long_names.rb --help
Usage: long_names [options]
        --xxx                        Long name
        --y1%, --z2#                 Two long names
$ ruby long_names.rb --xxx
[&quot;-xxx&quot;, true]
$ ruby long_names.rb --y1%
[&quot;--y1% or --z2#&quot;, true]
$ ruby long_names.rb --z2#
[&quot;--y1% or --z2#&quot;, true]</pre>

<p>A long name may be defined with both positive and negative senses.</p>

<p><a href="../File.html"><code>File</code></a> <code>long_with_negation.rb</code> defines an option that has both senses.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--[no-]binary&#39;</span>, <span class="ruby-string">&#39;Long name with negation&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-identifier">value</span>, <span class="ruby-identifier">value</span>.<span class="ruby-identifier">class</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby long_with_negation.rb --help
Usage: long_with_negation [options]
        --[no-]binary                Long name with negation
$ ruby long_with_negation.rb --binary
[true, TrueClass]
$ ruby long_with_negation.rb --no-binary
[false, FalseClass]</pre>

<h4 id="label-Mixing+Option+Names">Mixing Option Names<span><a href="#label-Mixing+Option+Names">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Many developers like to mix short and long option names, so that a short name is in effect an abbreviation of a long name.</p>

<p><a href="../File.html"><code>File</code></a> <code>mixed_names.rb</code> defines options that each have both a short and a long name.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-string">&#39;Short and long, no argument&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-yYYY&#39;</span>, <span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-string">&#39;Short and long, required argument&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-z [ZZZ]&#39;</span>, <span class="ruby-string">&#39;--zzz&#39;</span>, <span class="ruby-string">&#39;Short and long, optional argument&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--zzz&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby mixed_names.rb --help
Usage: mixed_names [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby mixed_names.rb -x
[&quot;--xxx&quot;, true]
$ ruby mixed_names.rb --xxx
[&quot;--xxx&quot;, true]
$ ruby mixed_names.rb -y
mixed_names.rb:12:in `&lt;main&gt;&#39;: missing argument: -y (OptionParser::MissingArgument)
$ ruby mixed_names.rb -y FOO
[&quot;--yyy&quot;, &quot;FOO&quot;]
$ ruby mixed_names.rb --yyy
mixed_names.rb:12:in `&lt;main&gt;&#39;: missing argument: --yyy (OptionParser::MissingArgument)
$ ruby mixed_names.rb --yyy BAR
[&quot;--yyy&quot;, &quot;BAR&quot;]
$ ruby mixed_names.rb -z
[&quot;--zzz&quot;, nil]
$ ruby mixed_names.rb -z BAZ
[&quot;--zzz&quot;, &quot;BAZ&quot;]
$ ruby mixed_names.rb --zzz
[&quot;--zzz&quot;, nil]
$ ruby mixed_names.rb --zzz BAT
[&quot;--zzz&quot;, &quot;BAT&quot;]</pre>

<h4 id="label-Option+Name+Abbreviations">Option Name Abbreviations<span><a href="#label-Option+Name+Abbreviations">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>By default, abbreviated option names on the command-line are allowed. An abbreviated name is valid if it is unique among abbreviated option names.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-n&#39;</span>, <span class="ruby-string">&#39;--dry-run&#39;</span>,) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--dry-run&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-d&#39;</span>, <span class="ruby-string">&#39;--draft&#39;</span>,) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--draft&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby name_abbrev.rb --help
Usage: name_abbrev [options]
    -n, --dry-run
    -d, --draft
$ ruby name_abbrev.rb -n
[&quot;--dry-run&quot;, true]
$ ruby name_abbrev.rb --dry-run
[&quot;--dry-run&quot;, true]
$ ruby name_abbrev.rb -d
[&quot;--draft&quot;, true]
$ ruby name_abbrev.rb --draft
[&quot;--draft&quot;, true]
$ ruby name_abbrev.rb --d
name_abbrev.rb:9:in `&lt;main&gt;&#39;: ambiguous option: --d (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dr
name_abbrev.rb:9:in `&lt;main&gt;&#39;: ambiguous option: --dr (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dry
[&quot;--dry-run&quot;, true]
$ ruby name_abbrev.rb --dra
[&quot;--draft&quot;, true]</pre>

<p>You can disable abbreviation using method <code>require_exact</code>.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-n&#39;</span>, <span class="ruby-string">&#39;--dry-run&#39;</span>,) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--dry-run&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-d&#39;</span>, <span class="ruby-string">&#39;--draft&#39;</span>,) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--draft&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">require_exact</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby no_abbreviation.rb --dry-ru
no_abbreviation.rb:10:in `&lt;main&gt;&#39;: invalid option: --dry-ru (OptionParser::InvalidOption)
$ ruby no_abbreviation.rb --dry-run
[&quot;--dry-run&quot;, true]</pre>

<h3 id="label-Option+Arguments">Option Arguments<span><a href="#label-Option+Arguments">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>An option may take no argument, a required argument, or an optional argument.</p>

<h4 id="label-Option+with+No+Argument">Option with No Argument<span><a href="#label-Option+with+No+Argument">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>All the examples above define options with no argument.</p>

<h4 id="label-Option+with+Required+Argument">Option with Required Argument<span><a href="#label-Option+with+Required+Argument">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Specify a required argument for an option by adding a dummy word to its name definition.</p>

<p><a href="../File.html"><code>File</code></a> <code>required_argument.rb</code> defines two options; each has a required argument because the name definition has a following dummy word.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x XXX&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-string">&#39;Required argument via short name&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-y&#39;</span>, <span class="ruby-string">&#39;--y YYY&#39;</span>, <span class="ruby-string">&#39;Required argument via long name&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>When an option is found, the given argument is yielded.</p>

<p>Executions:</p>

<pre>$ ruby required_argument.rb --help
Usage: required_argument [options]
    -x, --xxx XXX                    Required argument via short name
    -y, --y YYY                      Required argument via long name
$ ruby required_argument.rb -x AAA
[&quot;--xxx&quot;, &quot;AAA&quot;]
$ ruby required_argument.rb -y BBB
[&quot;--yyy&quot;, &quot;BBB&quot;]</pre>

<p>Omitting a required argument raises an error:</p>

<pre>$ ruby required_argument.rb -x
required_argument.rb:9:in `&lt;main&gt;&#39;: missing argument: -x (OptionParser::MissingArgument)</pre>

<h4 id="label-Option+with+Optional+Argument">Option with Optional Argument<span><a href="#label-Option+with+Optional+Argument">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Specify an optional argument for an option by adding a dummy word enclosed in square brackets to its name definition.</p>

<p><a href="../File.html"><code>File</code></a> <code>optional_argument.rb</code> defines two options; each has an optional argument because the name definition has a following dummy word in square brackets.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x [XXX]&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-string">&#39;Optional argument via short  name&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-y&#39;</span>, <span class="ruby-string">&#39;--yyy [YYY]&#39;</span>, <span class="ruby-string">&#39;Optional argument via long name&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>When an option with an argument is found, the given argument yielded.</p>

<p>Executions:</p>

<pre>$ ruby optional_argument.rb --help
Usage: optional_argument [options]
    -x, --xxx [XXX]                  Optional argument via short  name
    -y, --yyy [YYY]                  Optional argument via long name
$ ruby optional_argument.rb -x AAA
[&quot;--xxx&quot;, &quot;AAA&quot;]
$ ruby optional_argument.rb -y BBB
[&quot;--yyy&quot;, &quot;BBB&quot;]</pre>

<p>Omitting an optional argument does not raise an error.</p>

<h3 id="label-Argument+Values">Argument Values<span><a href="#label-Argument+Values">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>Permissible argument values may be restricted either by specifying explicit values or by providing a pattern that the given value must match.</p>

<h4 id="label-Explicit+Argument+Values">Explicit Argument Values<span><a href="#label-Explicit+Argument+Values">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>You can specify argument values in either of two ways:</p>
<ul><li>
<p>Specify values an array of strings.</p>
</li><li>
<p>Specify values a hash.</p>
</li></ul>

<h5 id="label-Explicit+Values+in+Array">Explicit Values in <a href="../Array.html"><code>Array</code></a><span><a href="#label-Explicit+Values+in+Array">&para;</a> <a href="#top">&uarr;</a></span></h5>

<p>You can specify explicit argument values in an array of strings. The argument value must be one of those strings, or an unambiguous abbreviation.</p>

<p><a href="../File.html"><code>File</code></a> <code>explicit_array_values.rb</code> defines options with explicit argument values.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-xXXX&#39;</span>, [<span class="ruby-string">&#39;foo&#39;</span>, <span class="ruby-string">&#39;bar&#39;</span>], <span class="ruby-string">&#39;Values for required argument&#39;</span> ) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-y [YYY]&#39;</span>, [<span class="ruby-string">&#39;baz&#39;</span>, <span class="ruby-string">&#39;bat&#39;</span>], <span class="ruby-string">&#39;Values for optional argument&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;-y&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby explicit_array_values.rb --help
Usage: explicit_array_values [options]
    -xXXX                            Values for required argument
    -y [YYY]                         Values for optional argument
$ ruby explicit_array_values.rb -x
explicit_array_values.rb:9:in `&lt;main&gt;&#39;: missing argument: -x (OptionParser::MissingArgument)
$ ruby explicit_array_values.rb -x foo
[&quot;-x&quot;, &quot;foo&quot;]
$ ruby explicit_array_values.rb -x f
[&quot;-x&quot;, &quot;foo&quot;]
$ ruby explicit_array_values.rb -x bar
[&quot;-x&quot;, &quot;bar&quot;]
$ ruby explicit_array_values.rb -y ba
explicit_array_values.rb:9:in `&lt;main&gt;&#39;: ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_array_values.rb -x baz
explicit_array_values.rb:9:in `&lt;main&gt;&#39;: invalid argument: -x baz (OptionParser::InvalidArgument)</pre>

<h5 id="label-Explicit+Values+in+Hash">Explicit Values in <a href="../Hash.html"><code>Hash</code></a><span><a href="#label-Explicit+Values+in+Hash">&para;</a> <a href="#top">&uarr;</a></span></h5>

<p>You can specify explicit argument values in a hash with string keys. The value passed must be one of those keys, or an unambiguous abbreviation; the value yielded will be the value for that key.</p>

<p><a href="../File.html"><code>File</code></a> <code>explicit_hash_values.rb</code> defines options with explicit argument values.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-xXXX&#39;</span>, {<span class="ruby-value">foo:</span> <span class="ruby-value">0</span>, <span class="ruby-value">bar:</span> <span class="ruby-value">1</span>}, <span class="ruby-string">&#39;Values for required argument&#39;</span> ) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-y [YYY]&#39;</span>, {<span class="ruby-value">baz:</span> <span class="ruby-value">2</span>, <span class="ruby-value">bat:</span> <span class="ruby-value">3</span>}, <span class="ruby-string">&#39;Values for optional argument&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;-y&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby explicit_hash_values.rb --help
Usage: explicit_hash_values [options]
    -xXXX                            Values for required argument
    -y [YYY]                         Values for optional argument
$ ruby explicit_hash_values.rb -x
explicit_hash_values.rb:9:in `&lt;main&gt;&#39;: missing argument: -x (OptionParser::MissingArgument)
$ ruby explicit_hash_values.rb -x foo
[&quot;-x&quot;, 0]
$ ruby explicit_hash_values.rb -x f
[&quot;-x&quot;, 0]
$ ruby explicit_hash_values.rb -x bar
[&quot;-x&quot;, 1]
$ ruby explicit_hash_values.rb -x baz
explicit_hash_values.rb:9:in `&lt;main&gt;&#39;: invalid argument: -x baz (OptionParser::InvalidArgument)
$ ruby explicit_hash_values.rb -y
[&quot;-y&quot;, nil]
$ ruby explicit_hash_values.rb -y baz
[&quot;-y&quot;, 2]
$ ruby explicit_hash_values.rb -y bat
[&quot;-y&quot;, 3]
$ ruby explicit_hash_values.rb -y ba
explicit_hash_values.rb:9:in `&lt;main&gt;&#39;: ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_hash_values.rb -y bam
[&quot;-y&quot;, nil]</pre>

<h4 id="label-Argument+Value+Patterns">Argument Value Patterns<span><a href="#label-Argument+Value+Patterns">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>You can restrict permissible argument values by specifying a <a href="../Regexp.html"><code>Regexp</code></a> that the given argument must match.</p>

<p><a href="../File.html"><code>File</code></a> <code>matched_values.rb</code> defines options with matched argument values.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--xxx XXX&#39;</span>, <span class="ruby-regexp">/foo/i</span>, <span class="ruby-string">&#39;Matched values&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby matched_values.rb --help
Usage: matched_values [options]
        --xxx XXX                    Matched values
$ ruby matched_values.rb --xxx foo
[&quot;--xxx&quot;, &quot;foo&quot;]
$ ruby matched_values.rb --xxx FOO
[&quot;--xxx&quot;, &quot;FOO&quot;]
$ ruby matched_values.rb --xxx bar
matched_values.rb:6:in `&lt;main&gt;&#39;: invalid argument: --xxx bar (OptionParser::InvalidArgument)</pre>

<h3 id="label-Keyword+Argument+into">Keyword Argument <code>into</code><span><a href="#label-Keyword+Argument+into">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>In parsing options, you can add keyword option <code>into</code> with a hash-like argument; each parsed option will be added as a name/value pair.</p>

<p>This is useful for:</p>
<ul><li>
<p>Collecting options.</p>
</li><li>
<p>Checking for missing options.</p>
</li><li>
<p>Providing default values for options.</p>
</li></ul>

<h4 id="label-Collecting+Options">Collecting Options<span><a href="#label-Collecting+Options">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Use keyword argument <code>into</code> to collect options.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-string">&#39;Short and long, no argument&#39;</span>)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-yYYY&#39;</span>, <span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-string">&#39;Short and long, required argument&#39;</span>)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-z [ZZZ]&#39;</span>, <span class="ruby-string">&#39;--zzz&#39;</span>, <span class="ruby-string">&#39;Short and long, optional argument&#39;</span>)
<span class="ruby-identifier">options</span> = {}
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>(<span class="ruby-value">into:</span> <span class="ruby-identifier">options</span>)
<span class="ruby-identifier">p</span> <span class="ruby-identifier">options</span>
</pre>

<p>Executions:</p>

<pre>$ ruby collected_options.rb --help
Usage: into [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby collected_options.rb --xxx
{:xxx=&gt;true}
$ ruby collected_options.rb --xxx --yyy FOO
{:xxx=&gt;true, :yyy=&gt;&quot;FOO&quot;}
$ ruby collected_options.rb --xxx --yyy FOO --zzz Bar
{:xxx=&gt;true, :yyy=&gt;&quot;FOO&quot;, :zzz=&gt;&quot;Bar&quot;}
$ ruby collected_options.rb --xxx --yyy FOO --yyy BAR
{:xxx=&gt;true, :yyy=&gt;&quot;BAR&quot;}</pre>

<p>Note in the last execution that the argument value for option <code>--yyy</code> was overwritten.</p>

<h4 id="label-Checking+for+Missing+Options">Checking for Missing Options<span><a href="#label-Checking+for+Missing+Options">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Use the collected options to check for missing options.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-string">&#39;Short and long, no argument&#39;</span>)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-yYYY&#39;</span>, <span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-string">&#39;Short and long, required argument&#39;</span>)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-z [ZZZ]&#39;</span>, <span class="ruby-string">&#39;--zzz&#39;</span>, <span class="ruby-string">&#39;Short and long, optional argument&#39;</span>)
<span class="ruby-identifier">options</span> = {}
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>(<span class="ruby-value">into:</span> <span class="ruby-identifier">options</span>)
<span class="ruby-identifier">required_options</span> = [<span class="ruby-value">:xxx</span>, <span class="ruby-value">:zzz</span>]
<span class="ruby-identifier">missing_options</span> = <span class="ruby-identifier">required_options</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">options</span>.<span class="ruby-identifier">keys</span>
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">missing_options</span>.<span class="ruby-identifier">empty?</span>
  <span class="ruby-identifier">fail</span> <span class="ruby-node">&quot;Missing required options: #{missing_options}&quot;</span>
<span class="ruby-keyword">end</span>
</pre>

<p>Executions:</p>

<pre>$ ruby missing_options.rb --help
Usage: missing_options [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby missing_options.rb --yyy FOO
missing_options.rb:11:in `&lt;main&gt;&#39;: Missing required options: [:xxx, :zzz] (RuntimeError)</pre>

<h4 id="label-Default+Values+for+Options">Default Values for Options<span><a href="#label-Default+Values+for+Options">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Initialize the <code>into</code> argument to define default values for options.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-string">&#39;Short and long, no argument&#39;</span>)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-yYYY&#39;</span>, <span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-string">&#39;Short and long, required argument&#39;</span>)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;-z [ZZZ]&#39;</span>, <span class="ruby-string">&#39;--zzz&#39;</span>, <span class="ruby-string">&#39;Short and long, optional argument&#39;</span>)
<span class="ruby-identifier">options</span> = {<span class="ruby-value">yyy:</span> <span class="ruby-string">&#39;AAA&#39;</span>, <span class="ruby-value">zzz:</span> <span class="ruby-string">&#39;BBB&#39;</span>}
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>(<span class="ruby-value">into:</span> <span class="ruby-identifier">options</span>)
<span class="ruby-identifier">p</span> <span class="ruby-identifier">options</span>
</pre>

<p>Executions:</p>

<pre>$ ruby default_values.rb --help
Usage: default_values [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby default_values.rb --yyy FOO
{:yyy=&gt;&quot;FOO&quot;, :zzz=&gt;&quot;BBB&quot;}</pre>

<h3 id="label-Argument+Converters">Argument Converters<span><a href="#label-Argument+Converters">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>An option can specify that its argument is to be converted from the default <code>String</code> to an instance of another class. There are a number of built-in converters.</p>

<p>Example: <a href="../File.html"><code>File</code></a> <code>date.rb</code> defines an option whose argument is to be converted to a <code>Date</code> object. The argument is converted by method Date#parse.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse/date&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--date=DATE&#39;</span>, <span class="ruby-constant">Date</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-identifier">value</span>, <span class="ruby-identifier">value</span>.<span class="ruby-identifier">class</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Executions:</p>

<pre>$ ruby date.rb --date 2001-02-03
[#&lt;Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)&gt;, Date]
$ ruby date.rb --date 20010203
[#&lt;Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)&gt;, Date]
$ ruby date.rb --date &quot;3rd Feb 2001&quot;
[#&lt;Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)&gt;, Date]</pre>

<p>You can also define custom converters. See <a href="./argument_converters_rdoc.html">Argument Converters</a> for both built-in and custom converters.</p>

<h3 id="label-Help">Help<span><a href="#label-Help">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p><code>OptionParser</code> makes automatically generated help text available.</p>

<p>The help text consists of:</p>
<ul><li>
<p>A banner, showing the usage.</p>
</li><li>
<p>Option short and long names.</p>
</li><li>
<p>Option dummy argument names.</p>
</li><li>
<p>Option descriptions.</p>
</li></ul>

<p>Example code:</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(
  <span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>,
  <span class="ruby-string">&#39;Adipiscing elit. Aenean commodo ligula eget.&#39;</span>,
  <span class="ruby-string">&#39;Aenean massa. Cum sociis natoque penatibus&#39;</span>,
  )
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(
  <span class="ruby-string">&#39;-y&#39;</span>, <span class="ruby-string">&#39;--yyy YYY&#39;</span>,
  <span class="ruby-string">&#39;Lorem ipsum dolor sit amet, consectetuer.&#39;</span>
)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(
  <span class="ruby-string">&#39;-z&#39;</span>, <span class="ruby-string">&#39;--zzz [ZZZ]&#39;</span>,
  <span class="ruby-string">&#39;Et magnis dis parturient montes, nascetur&#39;</span>,
  <span class="ruby-string">&#39;ridiculus mus. Donec quam felis, ultricies&#39;</span>,
  <span class="ruby-string">&#39;nec, pellentesque eu, pretium quis, sem.&#39;</span>,
  )
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>The option names and dummy argument names are defined as described above.</p>

<p>The option description consists of the strings that are not themselves option names; An option can have more than one description string. Execution:</p>

<pre>Usage: help [options]
    -x, --xxx                        Adipiscing elit. Aenean commodo ligula eget.
                                     Aenean massa. Cum sociis natoque penatibus
    -y, --yyy YYY                    Lorem ipsum dolor sit amet, consectetuer.
    -z, --zzz [ZZZ]                  Et magnis dis parturient montes, nascetur
                                     ridiculus mus. Donec quam felis, ultricies
                                     nec, pellentesque eu, pretium quis, sem.</pre>

<p>The program name is included in the default banner: <code>Usage: #{program_name} [options]</code>; you can change the program name.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">program_name</span> = <span class="ruby-string">&#39;help_program_name.rb&#39;</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Execution:</p>

<pre>$ ruby help_program_name.rb --help
Usage: help_program_name.rb [options]</pre>

<p>You can also change the entire banner.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">banner</span> = <span class="ruby-string">&quot;Usage: ruby help_banner.rb&quot;</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Execution:</p>

<pre>$ ruby help_banner.rb --help
Usage: ruby help_banner.rb</pre>

<p>By default, the option names are indented 4 spaces and the width of the option-names field is 32 spaces.</p>

<p>You can change these values, along with the banner, by passing parameters to OptionParser.new.</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>(
  <span class="ruby-string">&#39;ruby help_format.rb [options]&#39;</span>, <span class="ruby-comment"># Banner</span>
  <span class="ruby-value">20</span>,                               <span class="ruby-comment"># Width of options field</span>
  <span class="ruby-string">&#39; &#39;</span> <span class="ruby-operator">*</span> <span class="ruby-value">2</span>                               <span class="ruby-comment"># Indentation</span>
)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(
  <span class="ruby-string">&#39;-x&#39;</span>, <span class="ruby-string">&#39;--xxx&#39;</span>,
  <span class="ruby-string">&#39;Adipiscing elit. Aenean commodo ligula eget.&#39;</span>,
  <span class="ruby-string">&#39;Aenean massa. Cum sociis natoque penatibus&#39;</span>,
  )
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(
  <span class="ruby-string">&#39;-y&#39;</span>, <span class="ruby-string">&#39;--yyy YYY&#39;</span>,
  <span class="ruby-string">&#39;Lorem ipsum dolor sit amet, consectetuer.&#39;</span>
)
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(
  <span class="ruby-string">&#39;-z&#39;</span>, <span class="ruby-string">&#39;--zzz [ZZZ]&#39;</span>,
  <span class="ruby-string">&#39;Et magnis dis parturient montes, nascetur&#39;</span>,
  <span class="ruby-string">&#39;ridiculus mus. Donec quam felis, ultricies&#39;</span>,
  <span class="ruby-string">&#39;nec, pellentesque eu, pretium quis, sem.&#39;</span>,
  )
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
</pre>

<p>Execution:</p>

<pre>$ ruby help_format.rb --help
ruby help_format.rb [options]
  -x, --xxx            Adipiscing elit. Aenean commodo ligula eget.
                       Aenean massa. Cum sociis natoque penatibus
  -y, --yyy YYY        Lorem ipsum dolor sit amet, consectetuer.
  -z, --zzz [ZZZ]      Et magnis dis parturient montes, nascetur
                       ridiculus mus. Donec quam felis, ultricies
                       nec, pellentesque eu, pretium quis, sem.</pre>

<h3 id="label-Top+List+and+Base+List">Top List and Base List<span><a href="#label-Top+List+and+Base+List">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>An <code>OptionParser</code> object maintains a stack of OptionParser::List objects, each of which has a collection of zero or more options. It is unlikely that you’ll need to add or take away from that stack.</p>

<p>The stack includes:</p>
<ul><li>
<p>The <em>top list</em>, given by OptionParser#top.</p>
</li><li>
<p>The <em>base list</em>, given by OptionParser#base.</p>
</li></ul>

<p>When <code>OptionParser</code> builds its help text, the options in the top list precede those in the base list.</p>

<h3 id="label-Methods+for+Defining+Options">Methods for Defining Options<span><a href="#label-Methods+for+Defining+Options">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p>Option-defining methods allow you to create an option, and also append/prepend it to the top list or append it to the base list.</p>

<p>Each of these next three methods accepts a sequence of parameter arguments and a block, creates an option object using method OptionParser#make_switch (see below), and returns the created option:</p>
<ul><li>
<p>Method OptionParser#define appends the created option to the top list.</p>
</li><li>
<p>Method OptionParser#define_head prepends the created option to the top list.</p>
</li><li>
<p>Method OptionParser#define_tail appends the created option to the base list.</p>
</li></ul>

<p>These next three methods are identical to the three above, except for their return values:</p>
<ul><li>
<p>Method OptionParser#on is identical to method OptionParser#define, except that it returns the parser object <code>self</code>.</p>
</li><li>
<p>Method OptionParser#on_head is identical to method OptionParser#define_head, except that it returns the parser object <code>self</code>.</p>
</li><li>
<p>Method OptionParser#on_tail is identical to method OptionParser#define_tail, except that it returns the parser object <code>self</code>.</p>
</li></ul>

<p>Though you may never need to call it directly, here’s the core method for defining an option:</p>
<ul><li>
<p>Method OptionParser#make_switch accepts an array of parameters and a block. See <a href="optparse/option_params_rdoc.html">Parameters for New Options</a>. This method is unlike others here in that it:</p>
<ul><li>
<p>Accepts an <em>array of parameters</em>; others accept a <em>sequence of parameter arguments</em>.</p>
</li><li>
<p>Returns an array containing the created option object, option names, and other values; others return either the created option object or the parser object <code>self</code>.</p>
</li></ul>
</li></ul>

<h3 id="label-Parsing">Parsing<span><a href="#label-Parsing">&para;</a> <a href="#top">&uarr;</a></span></h3>

<p><code>OptionParser</code> has six instance methods for parsing.</p>

<p>Three have names ending with a “bang” (<code>!</code>):</p>
<ul><li>
<p>parse!</p>
</li><li>
<p>order!</p>
</li><li>
<p>permute!</p>
</li></ul>

<p>Each of these methods:</p>
<ul><li>
<p>Accepts an optional array of string arguments <code>argv</code>; if not given, <code>argv</code> defaults to the value of OptionParser#default_argv, whose initial value is ARGV.</p>
</li><li>
<p>Accepts an optional keyword argument <code>into</code> (see <a href="#label-Keyword+Argument+into">Keyword Argument into</a>).</p>
</li><li>
<p>Returns <code>argv</code>, possibly with some elements removed.</p>
</li></ul>

<p>The three other methods have names <em>not</em> ending with a “bang”:</p>
<ul><li>
<p>parse</p>
</li><li>
<p>order</p>
</li><li>
<p>permute</p>
</li></ul>

<p>Each of these methods:</p>
<ul><li>
<p>Accepts an array of string arguments <em>or</em> zero or more string arguments.</p>
</li><li>
<p>Accepts an optional keyword argument <code>into</code> and its value <em>into</em>. (see <a href="#label-Keyword+Argument+into">Keyword Argument into</a>).</p>
</li><li>
<p>Returns <code>argv</code>, possibly with some elements removed.</p>
</li></ul>

<h4 id="label-Method+parse-21">Method <code>parse!</code><span><a href="#label-Method+parse-21">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Method <code>parse!</code>:</p>
<ul><li>
<p>Accepts an optional array of string arguments <code>argv</code>; if not given, <code>argv</code> defaults to the value of OptionParser#default_argv, whose initial value is ARGV.</p>
</li><li>
<p>Accepts an optional keyword argument <code>into</code> (see <a href="#label-Keyword+Argument+into">Keyword Argument into</a>).</p>
</li><li>
<p>Returns <code>argv</code>, possibly with some elements removed.</p>
</li></ul>

<p>The method processes the elements in <code>argv</code> beginning at <code>argv[0]</code>, and ending, by default, at the end.</p>

<p>Otherwise processing ends and the method returns when:</p>
<ul><li>
<p>The terminator argument <code>--</code> is found; the terminator argument is removed before the return.</p>
</li><li>
<p>Environment variable <code>POSIXLY_CORRECT</code> is defined and a non-option argument is found; the non-option argument is not removed. Note that the <em>value</em> of that variable does not matter, as only its existence is checked.</p>
</li></ul>

<p><a href="../File.html"><code>File</code></a> <code>parse_bang.rb</code>:</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--xxx&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--yyy YYY&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--zzz [ZZZ]&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--zzz&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">ret</span> = <span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse!</span>
<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;Returned: #{ret} (#{ret.class})&quot;</span>
</pre>

<p>Help:</p>

<pre>$ ruby parse_bang.rb --help
Usage: parse_bang [options]
        --xxx
        --yyy YYY
        --zzz [ZZZ]</pre>

<p>Default behavior:</p>

<pre>$ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
[&quot;--xxx&quot;, true]
[&quot;--yyy&quot;, &quot;FOO&quot;]
[&quot;--zzz&quot;, &quot;BAR&quot;]
Returned: [&quot;input_file.txt&quot;, &quot;output_file.txt&quot;] (Array)</pre>

<p>Processing ended by terminator argument:</p>

<pre>$ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
[&quot;--xxx&quot;, true]
[&quot;--yyy&quot;, &quot;FOO&quot;]
Returned: [&quot;input_file.txt&quot;, &quot;output_file.txt&quot;, &quot;--zzz&quot;, &quot;BAR&quot;] (Array)</pre>

<p>Processing ended by non-option found when <code>POSIXLY_CORRECT</code> is defined:</p>

<pre>$ POSIXLY_CORRECT=true ruby parse_bang.rb --xxx input_file.txt output_file.txt -yyy FOO
[&quot;--xxx&quot;, true]
Returned: [&quot;input_file.txt&quot;, &quot;output_file.txt&quot;, &quot;-yyy&quot;, &quot;FOO&quot;] (Array)</pre>

<h4 id="label-Method+parse">Method <code>parse</code><span><a href="#label-Method+parse">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Method <code>parse</code>:</p>
<ul><li>
<p>Accepts an array of string arguments <em>or</em> zero or more string arguments.</p>
</li><li>
<p>Accepts an optional keyword argument <code>into</code> and its value <em>into</em>. (see <a href="#label-Keyword+Argument+into">Keyword Argument into</a>).</p>
</li><li>
<p>Returns <code>argv</code>, possibly with some elements removed.</p>
</li></ul>

<p>If given an array <code>ary</code>, the method forms array <code>argv</code> as <code>ary.dup</code>. If given zero or more string arguments, those arguments are formed into array <code>argv</code>.</p>

<p>The method calls</p>

<pre class="ruby"><span class="ruby-identifier">parse!</span>(<span class="ruby-identifier">argv</span>, <span class="ruby-value">into:</span> <span class="ruby-identifier">into</span>)
</pre>

<p>Note that environment variable <code>POSIXLY_CORRECT</code> and the terminator argument <code>--</code> are honored.</p>

<p><a href="../File.html"><code>File</code></a> <code>parse.rb</code>:</p>

<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;optparse&#39;</span>
<span class="ruby-identifier">parser</span> = <span class="ruby-constant">OptionParser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--xxx&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--xxx&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--yyy YYY&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--yyy&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">parser</span>.<span class="ruby-identifier">on</span>(<span class="ruby-string">&#39;--zzz [ZZZ]&#39;</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">value</span><span class="ruby-operator">|</span>
  <span class="ruby-identifier">p</span> [<span class="ruby-string">&#39;--zzz&#39;</span>, <span class="ruby-identifier">value</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">ret</span> = <span class="ruby-identifier">parser</span>.<span class="ruby-identifier">parse</span>(<span class="ruby-constant">ARGV</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-node">&quot;Returned: #{ret} (#{ret.class})&quot;</span>
</pre>

<p>Help:</p>

<pre>$ ruby parse.rb --help
Usage: parse [options]
        --xxx
        --yyy YYY
        --zzz [ZZZ]</pre>

<p>Default behavior:</p>

<pre>$ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
[&quot;--xxx&quot;, true]
[&quot;--yyy&quot;, &quot;FOO&quot;]
[&quot;--zzz&quot;, &quot;BAR&quot;]
Returned: [&quot;input_file.txt&quot;, &quot;output_file.txt&quot;] (Array)</pre>

<p>Processing ended by terminator argument:</p>

<pre>$ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
[&quot;--xxx&quot;, true]
[&quot;--yyy&quot;, &quot;FOO&quot;]
Returned: [&quot;input_file.txt&quot;, &quot;output_file.txt&quot;, &quot;--zzz&quot;, &quot;BAR&quot;] (Array)</pre>

<p>Processing ended by non-option found when <code>POSIXLY_CORRECT</code> is defined:</p>

<pre>$ POSIXLY_CORRECT=true ruby parse.rb --xxx input_file.txt output_file.txt -yyy FOO
[&quot;--xxx&quot;, true]
Returned: [&quot;input_file.txt&quot;, &quot;output_file.txt&quot;, &quot;-yyy&quot;, &quot;FOO&quot;] (Array)</pre>

<h4 id="label-Method+order-21">Method <code>order!</code><span><a href="#label-Method+order-21">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Calling method OptionParser#order! gives exactly the same result as calling method OptionParser#parse! with environment variable <code>POSIXLY_CORRECT</code> defined.</p>

<h4 id="label-Method+order">Method <code>order</code><span><a href="#label-Method+order">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Calling method OptionParser#order gives exactly the same result as calling method OptionParser#parse with environment variable <code>POSIXLY_CORRECT</code> defined.</p>

<h4 id="label-Method+permute-21">Method <code>permute!</code><span><a href="#label-Method+permute-21">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Calling method OptionParser#permute! gives exactly the same result as calling method OptionParser#parse! with environment variable <code>POSIXLY_CORRECT</code> <em>not</em> defined.</p>

<h4 id="label-Method+permute">Method <code>permute</code><span><a href="#label-Method+permute">&para;</a> <a href="#top">&uarr;</a></span></h4>

<p>Calling method OptionParser#permute gives exactly the same result as calling method OptionParser#parse with environment variable <code>POSIXLY_CORRECT</code> <em>not</em> defined.</p>

</main>

</div>  <!--  class='wrapper hdiv' -->


<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a></p>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.4.0.</p>
<p>Based on <a href="https://github.com/ged/darkfish/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.</p>

  
    <p><p><a href="https://ruby-doc.org">Ruby-doc.org</a> is a service of <a href="https://jamesbritt.com">James Britt</a> and <a href="https://neurogami.com">Neurogami</a>, purveyors of fine <a href='https://jamesbritt.bandcamp.com/'>dance noise</a></p>
</p>
  
  </footer>

<script type="text/javascript">


  let ads  = $("#carbonads-container").children().detach();


  function swapMode() {
    var cookieName = 'darkmode';
    var cssDarkmode = Cookies.get(cookieName);
    console.log("***** swapMode! " + cssDarkmode + " *****");


    if (cssDarkmode == "true") {
      console.log("We have dark mode, set the css to light ...");
      $('#rdoccss').attr("href", defaultModeCssHref);
      $('#cssSelect').text("Dark mode");
      cssDarkmode = "false";
      console.log("swapMode! Now set cookie to " + cssDarkmode);
      Cookies.set(cookieName, cssDarkmode);

    } else {
      console.log("We not have dark mode, set the css to dark ...");
      $('#rdoccss').attr("href", darkModeCsseHref);
      $('#cssSelect').text("Light mode");
      cssDarkmode = "true";
      console.log("swapMode! Now set cookie to " + cssDarkmode);
      Cookies.set(cookieName, cssDarkmode);

    }

    console.log("  --------------- ");
  }


const vueCssApp = new Vue({
el: '#menubar',
data: {
isDark: false
},
methods: {
toggleClass: function(event){
this.isDark = !this.isDark;
}
}
})

const vueApp = new Vue({
el: '#vapp',
data: { 
isOpen: true
},

mounted() {
this.handleResize();
this.manage_mob_classes();
window.addEventListener('resize', this.handleResize)
//this.isOpen !=  (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent));
},
destroyed() {
window.removeEventListener('resize', this.handleResize)
},
created() {
//manage_mob_classes();
},

methods : {
isMobile() {
  return (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent));
},

  handleResize() {
    if (!this.isMobile()) {
      this.isOpen = window.innerWidth > 800;
    }
  },

  manage_mob_classes() {
    if (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)) {
      $("nav").addClass("mob_nav");
      $("main").addClass("mob_main");
      $("#extraz").addClass("mob_extraz");
      $("#carbonads-container").addClass("mob_carbonads-container");
      this.isOpen  = false;
    } else {
      $("nav").removeClass("mob_nav") 
        $("main").removeClass("mob_main");
      $("#extraz").removeClass("mob_extraz");
      $("#carbonads-container").removeClass("mob_carbonads-container");
      this.isOpen  = true;
    }
  },

  toggleNav() {
    this.isOpen =! this.isOpen ;
    // alert("Toggle nav!");
    console.log("toggleNav() click: " + this.isOpen );
  }
}
})

$("#carbonads-container").append(ads);


$(function() {

    var darkmode = Cookies.get("darkmode");
    console.log("Document ready: " + darkmode);

    if ( darkmode  == "true" ) {
      $('#cssSelect').text("Light mode");
    } else {
      $('#cssSelect').text("Dark mode");
     }

    $('body').css('display','block');
    });

</script>

    
  </body> 
</html>

